/*
 *  Copyright (C) 2011 glauco
 * 
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 * 
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 * 
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.balisunrise.common;

import java.io.Serializable;

/**
 * Interface padrão para seleção de entidades.
 * O SelectionLoader utiliza um EntityLoader para busca entidades com um
 * Query de um Queryable, chamando o EntitySelection quando a query retornor
 * mais de um registro.
 *
 * @author glauco
 */
public interface SelectionLoader extends Basic, DAOProvider{

    /**
     * Atribui a mensagem de entidade não encontrada.
     * 
     * @param message
     */
    public void setNotFoundMessage(String message);

    /**
     * Retorna a mensagem de entidade não encontrada.
     *
     * @return
     */
    public String getNotFoundMessage();

    /**
     * Atribui o queryable.
     *
     * @param queryable
     */
    public void setQueryable(Queryable queryable);

    /**
     * Retorna o queryable.
     *
     * @return
     */
    public Queryable getQueryable();

    /**
     * Atribui o EntitySelection.
     *
     * @param entitySelection
     */
    public void setEntitySelection(EntitySelection entitySelection);

    /**
     * Retorna o EntitySelection.
     * 
     * @return
     */
    public EntitySelection getEntitySelection();

    /**
     * Ação que seleciona uma entidade.<br>
     * Carrega atravéz do Queryable e um EntityLoader as entidades.<br>
     * Do retorno do EntityLoader se faz:<br><p>
     *   - Caso não retorne nenhuma entidade, é retornado nulo;<br>
     *   - Caso retorne uma unica entidade é retornado a mesma;<br>
     *   - Case retorne mais de uma entidade é chamado o EntitySelection e
     *      retornado a entidade selecionada.<br>
     *
     * @return A entitidade selecionada ou nulo.
     * @exception NotFoundException Quando não é encontrado nenhuma entidade
     * para o(s) valor(es) utilizado(s) na pesquisa.
     * @exception NotModifiedException Quando o queryable utilizado para
     * pesquisar não foi modificado.
     */
    public Serializable selectEntity() 
            throws NotFoundException, NotModifiedException;

    /**
     * Atribui o EntityList.<br>
     * O EntityList será utilizado para construção de um EntityLoader,
     * caso o EntityLoader não seja atribuído.
     */
    public void setEntityList(EntityList entityList);

    /**
     * Atribui o EntityLoader.<br>
     * O EntityLoader é utilizado para carregar as entidades.
     */
    public void setEntityLoader(EntityLoader entityLoader);
}
